Using the Grid List Box nodes

Use the Grid List Box nodes to create scrollable lists of items arranged in a grid. As you add items to a Grid List Box node, the Grid List Box node places them either in its first row or column:

• When the items in the Grid List Box node reach the set width or height of the Grid List Box node, the Grid List Box node places the items in the next row or column.
• When there are more items than fit in the width and height you set for a grid list box, the items become visible as you scroll the Grid List Box node.

To select an item in a Grid List Box node click or tap the item.

The Grid List Box node arranges its items based on what you set in the Layout Direction property:

• Right to arrange the items along the x axis.
  When adding items, the Grid List Box node places each new item to the right of the item preceding it. When an item reaches or exceeds the width of the Grid List Box node, the Grid List Box node places that item into a new row.
  Users can scroll the Grid List Box node on the y axis.
  
• Down to arrange the items along the y axis.
  When adding items, the Grid List Box node places each new item below the item preceding it. When an item reaches or exceeds the height of the Grid List Box node, the Grid List Box node places that item into a new column.
  Users can scroll the Grid List Box node on the x axis.
  

When a Grid List Box node has focus use:

• The ↑ (Up Arrow) and ↓ (Down Arrow) keyboard keys to scroll the list items in a vertical list box
• The → (Right Arrow) and ← (Left Arrow) keyboard keys to scroll the list items in a horizontal list box
• The Home keyboard key selects the first list item
• The End keyboard key selects the last list item
• The Page Up and Page Down keyboard keys go to the beginning and end of the visible area of a list box

Note that items in all list box nodes (Grid List Box nodes and Trajectory List Box 3D node) are not its child nodes, even though in Kanzi Studio it seems so when you add items to a list box. Because list box items are not child nodes of a list box, you cannot refer to these items from outside of a list box using paths or aliases. If you need to refer from a list box item to an object outside of a list box, use bindings and aliases. See and Navigating to Page nodes from a Grid List Box node.

Creating a Grid List Box node

To create a Grid List Box node:

1. In the Project press Alt and right-click the node where you want to create a Grid List Box node and select either Grid List Box 3D, or Grid List Box 2D.
   Note that you can create a 3D node only inside 3D nodes, and 2D node only inside 2D nodes.
   
2. In the Project add items to the Grid List Box node.
   Use a data source to add items to a List Box node. See Using a data source.
   For example, to create a contact list, add several nodes which represent the contacts in the list. See Using the List Box Item Container prefabs.
   As you add items, the Grid List Box node arranges them in a grid from the top-left towards the bottom-right corner of the Grid List Box node. See Setting how a Grid List Box node arranges its items.
   To browse the items in a Grid List Box node, in the Preview click and drag the items in the Grid List Box node.
   
3. In the Project select the Grid List Box node and in the Properties set the Layout Height and Layout Width properties.
   You set the area in which the items in the Grid List Box node are visible. If all items in the Grid List Box node do not fit in the area, Kanzi clips those items which do not fit. The user can scroll the Grid List Box node to access all items.
   
4. (Optional) If you cannot see the content you added to a Grid List Box node or the content does not fully fit, add and set the Cell Height and Cell Width properties.
   You set the area reserved for each element inside the list box. The cell size clips the items if the items do not fit in the cell.
   
5. (Optional) In the Preview click to enter the Analyze mode, right-click , and select Debug objects.
   This way you visualize the cells of the Grid List Box node.
   

Setting how a Grid List Box node arranges its items

You can set the Grid List Box node so that it arranges its items either along the x or y axis.

To set how a Grid List Box arranges its items:

1. Create a Grid List Box node and add items to it. See Creating a Grid List Box node.
2. In the Properties set the Layout Direction property to either:
   • Right to arrange the items along the x axis.
     When adding items, the Grid List Box node places each new item to the right of the item preceding it. When an item reaches or exceeds the width of the Grid List Box node, the Grid List Box node places that item into a new row. Use the Layout Width and Layout Height properties to set the size of the Grid List Box node area.
     Users can scroll the Grid List Box node on the y axis.
     
   • Down to arrange the items along the y axis.
     When adding items, the Grid List Box node places each new item below the item preceding it. When an item reaches or exceeds the height of the Grid List Box node, the Grid List Box node places that item into a new column. Use the Layout Width and Layout Height properties to set the size of the Grid List Box node area.
     Users can scroll the Grid List Box node on the x axis.
     

Bringing the selected item to the center of the list box

You can set a Grid List Box node to bring the item to the center of the list box area when a user clicks or taps that item.

To set items in a Grid List Box node to the center when the user selects them:

1. Create a Grid List Box node and add items to it. See Creating a Grid List Box node.
2. In the Properties add the Selection Behavior property and set it to Bring Center.
   You set the Grid List Box node to scroll an item to the center of the node area when the user selects that item. The Grid List Box node centers its items based on the value you set in the Layout Direction property. See Setting how a Grid List Box node arranges its items.
   
3. In the Properties add and set:
   • Item Area Begin to the offset where you want the area for the items in the Grid List Box node to begin.
     For example, set it to 0.4.
   • Item Area End to the offset where you want the area for the items in the Grid List Box node to end.
     For example, set it to 0.6.

   Use the Item Area Begin and Item Area End properties to:

   • Grid List Box 2D. Set the items at the beginning and end of the list to also align to the center of the list when the user selects one of those items. For example, if the Grid List Box node has five items visible at a time, each of those items takes up 0.2 of the total area of the Grid List Box node. The centermost item takes up 0.1 of the space above it and 0.1 of the space below it.
   • Grid List Box 3D. Set the value of the Visible Amount In Parent property. Use the Visible Amount In Parent property to set shaders to change the appearance of an item based on the location of that object in the list box. For example, if you use the Visible Amount In Parent property to gradually change the visibility of an item, set the Item Area Begin property to a larger value and the Item Area End property to a smaller value. This way you limit the area where that item is visible.

   

Binding to properties outside of a Grid List Box node

Use an alias when you want to bind a property of a list box item to a property of a node outside of the list box.

For example, if you have a Grid List Box 3D or a Trajectory List Box 3D node with a Text Block 3D node item and want to set the Text property value of the Text Block 3D node to a value of an Empty Node 3D node property that is not in the list box:

1. In the Project press Alt and right-click the nodes that contain the property to which you want to bind and select Alias. See Using aliases.
   For example, create an alias for the Empty Node 3D node.
2. In the Dictionaries make sure that the aliases you created are in the resource dictionary that the list box node can access.
   For example, place all aliases to the resource dictionary of the Screen node, or create a resource dictionary in the list box node and place the aliases to that resource dictionary. See Using resource dictionaries.
3. Create the binding:
   1. In the Project select the node inside the list box node from which you want to bind to a node outside of the list box node.
   2. In the Properties add the Bindings property and create the binding using the alias to bind to the property in a node outside of the list box node.
      For example, in the Text Block 3D node create a binding to the Empty Node 3D node using the alias you created in the first step. See Bindings expressions reference.
      For example, use this binding expression:

      {#Empty Node 3D/TextBlockConcept.Text}

      
      The Text property in the Text Block 3D node gets the value of the Text property from the Empty Node 3D node.
   3. Click Save.

Navigating to Page nodes from a Grid List Box node

Use an alias when you want to navigate to a Page node from a node that is inside a list box node. For example, if you use a Grid List Box or a Trajectory List Box 3D node to create an address book and want to show the content of an address book entry in a Page node.

To navigate to Page nodes from a list box node:

1. In the Project press Alt and right-click each Page node to which you want to navigate to and select Alias.
   Kanzi Studio creates an alias that points to the node from which you created it, and places the alias to the nearest resource dictionary.
   
2. In the Dictionaries make sure that the aliases you created are in the resource dictionary that the list box node can access.
   For example, place all aliases to the resource dictionary of the Screen node, or create a resource dictionary in the list box node and place the aliases to that resource dictionary. See Using resource dictionaries.
   
3. Add and set the Navigate to Page action:
   1. In the Project in the list box node select the node that contains the trigger you want to use to navigate to one of the Page nodes for which you created the alias in the first step.
      
   2. In the Node Components > Triggers section in the trigger you want to use to navigate to the Page node add the Navigate to Page action.
      
   3. In the Navigate to Page settings window set the Item property to the alias of the Page node to which you want to navigate and click Save.
      All aliases start with a # sign.
      

In the Preview when you click the node that contains the Navigate to Page action, you activate the Page node selected in the action.

Setting the appearance of a Grid List Box 2D node

To set the appearance of 2D nodes:

• You can fill 2D nodes with a solid color, a texture, or a material. See Adjusting the appearance of 2D nodes.
• You can rotate a 2D node around all three axes to create a 3D perspective effect. See Creating a 3D perspective effect for 2D nodes.
• You can apply custom rendering to 2D nodes to create post-processing effects. See Applying custom rendering to 2D nodes.

Using the Grid List Box 3D node in the API

To create a Grid List Box 3D:

// Create a Grid List Box 3D named MyListBox.
GridListBox3DSharedPtr gridListBox = GridListBox3D::create(domain, "MyListBox");

To configure the grid area:

// Make each grid cell be a 1x1x1 cube.
gridListBox->setCellWidth(1.0f);
gridListBox->setCellHeight(1.0f);
gridListBox->setDepth(1.0f);
// Make the grid contain three rows that are filled column by column.
gridListBox->setHeight(3.0f);
gridListBox->setDirection(GridListBoxConcept::GridDirectionDown);
// Make the grid contain 10 columns. Items that are dragged beyond these columns are made invisible.
gridListBox->setWidth(10.0f);
// Change the resting position when the list is scrolled to the beginning or end, so that items are not right at the grid edge.
gridListBox->setItemAreaBegin(0.2f);
gridListBox->setItemAreaEnd(0.8f);

To add items to the list box:

// Create cube meshes and add them as items of the list box.
// Items on the grid appear in the order you add them to the list.
Model3DSharedPtr item1 = Model3D::createCube(domain, "item1", 1.0f, ThemeRed);
Model3DSharedPtr item2 = Model3D::createCube(domain, "item2", 1.0f, ThemeGreen);
Model3DSharedPtr item3 = Model3D::createCube(domain, "item3", 1.0f, ThemeBlue);
Model3DSharedPtr item4 = Model3D::createCube(domain, "item4", 1.0f, ThemeOrange);
Model3DSharedPtr item5 = Model3D::createCube(domain, "item5", 1.0f, ThemeYellow);
gridListBox->addItem(item1);
gridListBox->addItem(item2);
gridListBox->addItem(item3);
gridListBox->addItem(item4);
gridListBox->addItem(item5);

For details, see the GridListBox3D class in the API reference.

Using the Grid List Box 2D node in the API

To create a Grid List Box 2D:

// Create a Grid List Box 2D named MyListBox.
GridListBox2DSharedPtr gridListBox = GridListBox2D::create(domain, "MyListBox");

To configure the grid area:

// Make each grid cell be a 100x100 square.
gridListBox->setCellWidth(100.0f);
gridListBox->setCellHeight(100.0f);
// Make the grid contain three rows that are filled column by column.
gridListBox->setHeight(300.0f);
gridListBox->setDirection(GridListBoxConcept::GridDirectionDown);
// Make the grid contain 10 columns. Items that are dragged beyond these columns are made invisible.
gridListBox->setWidth(1000.0f);
// Change the resting position when the list is scrolled to the beginning or end, so that items are not right at the grid edge.
gridListBox->setItemAreaBegin(0.2f);
gridListBox->setItemAreaEnd(0.8f);

To add items to the list box:

// Create images and add them as items of the list box.
// Items on the grid appear in the order you add them to the list.
for (int i = 0; i < 5; ++i)
{
    Image2DSharedPtr item = Image2D::create(domain, "item" + to_string(i));
    item->setImage(item->acquireResource<Texture>(ResourceID("DefaultTexture")));
    // Make the images shrink to the cell size.
    item->setHorizontalAlignment(Node::HorizontalAlignmentStretch);
    item->setVerticalAlignment(Node::VerticalAlignmentStretch);
    gridListBox->addItem(item);
}

For details, see the GridListBox2D class in the API reference.

See also

Using the Trajectory List Box 3D node

Using the Grid Layout nodes

Using the List Box Item Container prefabs

Open topic with navigation